El Mac 1/Magazine.iso/EL MAC 1/Shareware/Utilities/INITGestalt Inspector 1.0/INITGestalt Inspector/INITGestalt Inspector.rsrc/TEXT_5000.txt

Text File | 1995-08-08 | 11.1 KB | 279 lines

Alessandro Levi Montalcini
C.so Re Umberto 10
10121 Torino
Italy
e-mail: [e-mail]
ftp://ftp.alpcom.it/software/mac/LMontalcini


 



INITGestalt Inspector 1.0 docs - August 1995

• Introduction
◊  INITGestalt Inspector is a free drag & drop utility that displays the INITGestalt table returned by INITGestalt-aware extensions, control panels and applications. End users can use the INITGestalt Inspector to extract some basic information about their INITGestalt-aware extensions, while programmers can use it to verify that their software is INITGestalt compliant. If you don’t know anything about the INITGestalt proposal, you may want to read the complete documentation below.

• INITGestalt
◊  Here’s a copy of the INITGestalt proposal by Jeremy Roussak and Rene G.A. Ros:
________________________________________________________________

INITGestalt: a proposal
=======================

Version 1.0
Last modified: March 21st, 1995 / 21 March 1995

It is often useful for an extension, or indeed an application, to know
whether certain other extensions are running (the term "extensions"
primarily includes system extensions, control panels and background-only
applications, although there is no reason why it should not include
ordinary applications). The reasons could be to take evasive action to
avoid conflicts with other extensions, to co-operate with another
extension, perhaps by using that extension's features, or possibly to
disable similar features.
Another useful application is to allow extension manager type of software
to retrieve information they want to know in order to improve their
features and usefullness to the users.

Fortunately, since system 6.0.4 a system-supported mechanism has existed
whereby this could be achieved: Gestalt.

We would therefore like to propose a standard to which writers of software
could adhere. The success of ShowINIT indicates that such a de facto
standard can emerge.

1.    Every extension should register a Gestalt selector equal to its
    signature. If Gestalt subsequently returns gestaltUndefSelectorErr, the
    extension is not loaded.

2.    The value returned by Gestalt is of suffix type Table: that is, a
    pointer to more data. The block to which the pointer points is already
    allocated in the system heap and should not be disposed, since it might
    be part of a larger memory block. The returned value may be nil if the
    installed software is disabled and removed from memory, or when the
    application has quit. The Gestalt definition function which returns the
    value should not move memory and should be safe to be called at
    interrupt time.

3.    The minimum table returned should contain the record described below.
    The table returned is read-only.

    C:
    typedef struct
    {
        OSType            recType;        // always kGestaltRecordType
        NumVersion        recVersion;        // version of the record format
        NumVersion        igVersion;        // version of installed software
        ulong            igStdAttr;        // standard defined attribute bits
        ulong            reserved1;        // reserved, more attribute bits
        ulong            igCustomAttr;    // custom defined attribute bits
        ProcessSerialNumber    igProcess;    // PSN of installer
        ISAType            igPlatformType;    // platform type
        byte            reserved2;        // reserved
        ushort            reserved3;        // reserved
        ulong            igRefCon        // private pointer or handle
    } INITGestaltRec, *INITGestaltRecPtr, **INITGestaltRecHandle;

    enum
    {
        kIGRecType                = 'JRRR',
        kIGRecCurrentVersion    = $01008000,

        //    bit constants for the stdAttr field
        kIGEnabled                = 0,
        kIGDebugVersion,
        kIGDebugEnabled,
        kIGAcceptsAEvents,
    }


    PASCAL:
    type
    INITGestaltRec =    record
        recType:        OSType;            {always kGestaltRecordType}
        recVersion:        NumVersion;        {version of the record format}
        igVersion:        NumVersion;        {version of installed software}
        igStdAttr:        LongInt;        {standard defined attribute bits}
        reserved1:        LongInt;        {reserved, more attribute bits}
        igCustomAttr:    LongInt;        {custom defined attribute bits}
        igProcess:        ProcessSerialNumber;    {PSN of installer}
        igPlatformType:    ISAType;        {platform type}
        reserved2:        Byte;            {reserved}
        reserved3:        Integer;        {reserved}
        igRefCon:        LongInt;        {private pointer or handle}
        end;

    INITGestaltRecPtr = ^INITGestaltRec;
    INITGestaltRecHandle = ^INITGestaltRecPtr;

    const
        kIGRecType                = 'JRRR';
        kIGRecCurrentVersion    = $01008000;

        {bit constants for the stdAttr field}
        kIGEnabled                = 0;
        kIGDebugVersion            = 1;
        kIGDebugEnabled            = 2;
        kIGAcceptsAEvents        = 3;


recType
    This field must always contain 'JRRR' (kIGRecType) to indicate it
    supports the INITGestaltRec as defined by this standard.

recVersion
    Contains a version number indicating the version of the INITGestalt
    standard to which the INITGestaltRec complies. This field should be
    filled using the kIGRecCurrentVersion constant. The version number is
    in the same format as the first four bytes of a 'vers' resource.
    This version number changes when fields are added and also when more
    attribute bits are defined.

version
    Holds the version of installed software in the same format as the first
    four bytes of a 'vers' resource.

stdAttr
    Holds attribute bits defined by this standard to indicate certain
    capabilities. The following bits are currently defined, the others must
    always be set to zero.

    kIGEnabled
        If set, the installed software is currently enabled.

    kIGDebugVersion
        If set, the installed software is a debugging version.

    kIGDebugEnabled
        If set, the installed software is a debugging version and supports
        a debug mode which can be turned on and off (this bit can never be
        set if kIGDebugVersion is unset).

    kIGAcceptsAEvents
        If set, the installed software can accept AppleEvents

reserved1
    Reserved, possibly for more attribute bits defined by this standard.
    Should be set to zero.

custAttr
    Holds attribute bits defined by the software which installed this
    selector pointing to the INITGestaltRec record. The developer can use
    this field for attribute bits only and should define them with the
    documentation as much as possible. Undefined bits must always be set to
    zero.

process
    Holds the Process Serial Number of the process which installed this
    selector. If no process is associated this field must be zero
    (kNoProcess). The other Process Manager constants kSystemProcess and
    kCurrentProcess should not be used.

platform
    This returns the ISAType indicating if the software is native PowerPC
    code or 68K code. Use GetCurrentISA to get the current ISAType at
    compile time. This is either kM68kISA (0) for the M680x0 system
    architecture or kPowerPCISA (1) for the PowerPC system architecture.

reserved2
reserved3
    Reserved for future use. Should be set to zero.

refCon
    Pointer or Handle to another block with custom and/or private data.
    Should be nil if not used. In any event, the caller should not attempt
    to dispose of the data block to which refCon points. One obvious use
    of refCon would be to allow communication between a control panel and
    its INIT component.

4.    If your software installs a selector which adopts this standard, you
    should email your documentation, which includes a description of the
    custom fields, to Rene G.A. Ros for inclusion with the Gestalt
    Selectors List (GSL). An entry in the GSL would look like this:

    =============================================================
    SWVE (SimpleWave ext [1.0b1] by Rene G.A. Ros)
         gestaltSimpleWaveTable
         Returns a pointer to an INITGestalt structure.

         const
         gestaltSimpleWaveTable = 'SWVE';
    =============================================================



The code required to implement the basic functionality would be very small
and very easy to write.

Comments on this proposal please: post rather than email.



Jeremy Roussak ([e-mail])
Rene G.A. Ros ([e-mail])


The following persons contributed ideas and corrections for which we want
to thank them:
    Dave Ely ([e-mail])
    Bill Hofmann ([e-mail])
    ??? Grobbins ([e-mail])
    John Mancino ([e-mail])
    Jens Miltner ([e-mail])
    Alessandro Levi Montalcini ([e-mail])
    Fabrizio Oddone ([e-mail])
    Quinn "The Eskimo" ([e-mail])
    Caleb Strockbine ([e-mail])
    Chris Thomas ([e-mail])
    Mark R. Valence ([e-mail])
    Hans Verbrugge ([e-mail])
    Matthew Xavier Mora ([e-mail])
    and many others who discussed the merits of the Component Manager! :-)

---------------------------------------------------------------------------

Changes
    1.0 (21 march 1995)
    -    renamed most fields to have them start with ig.

    1.0b2 (20 february 1995)
    Because implementing the Control function with passing pointers to
    different heap zones is considered a compatibility problem with future
    System software, the Control function is deleted. A future proposal may
    implement controlling functions using either the Component Manager or
    the PPC Toolbox.
    -    added kIGReserved bit for stdAttr field.
    -    added platform field and unused fields for alignment.
    -    removed kIGPPCNative bit for stdAttr field, replaced by platform
        field.
    -    removed text about adding additional private data to the record.
    -    some minor changes and corrections to the text.

    1.0b1 (31 January 1995)
    -    changed recVersion to NumVersion type.

---------------------------------------------------------------------------
History
This proposal was initially written in 1992 for use by extensions by
Jeremy Roussak based on an idea by Rene Ros. It never saw daylight because
of other projects. After almost two year we saw some need for changes and
to make it generally usuable for applications as well.
________________________________________________________________

• Version history
◊  1.0 - First public release, uses version 1.0 of the INITGestalt proposal by Jeremy Roussak and Rene G.A. Ros.

• Distribution
◊  INITGestalt Inspector is ©1994-95 Alessandro Levi Montalcini. It can be freely distributed as long as it is not modified and there’s no charge for it, but it may not be included in any commercial package without my consent.
◊  You may find the latest version of all my shareware programs by anonymous ftp to ftp.alpcom.it, inside the /software/mac/LMontalcini directory. The complete ShareDisk package, which contains all my stuff and can be registered at a very low price, is also available there.
◊  All online services and bulletin boards may make it available to their users at no charge other than the normal connection fees.
◊  All non-profit user groups may distribute it at no charge.
◊  All magazines may publish it on floppy disk without asking me first, as long as I get a copy of the issue containing my software.
◊  All CD-ROM shareware collections and CD-ROM magazines may include it without my prior consent, as long as I get either a copy of the CD-ROM or an offer to buy the CD-ROM at a discounted price.
◊  All redistribution companies such as Educorp may distribute it, as long as I get a copy of each media containing my software and a catalog of the company’s offerings (where applicable).

• Disclaimer
◊  INITGestalt Inspector shouldn’t cause any damage, but you’re using it at your own risk. As an independent software developer, I can make no warranties whatsoever on it.